-
Notifications
You must be signed in to change notification settings - Fork 71
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Relax entity requirements #45
Conversation
* Allows more efficient encoding * Does not force the representation to tightly couple child entities to parent entities via required `rel`.
An OPTIONAL |
Can entities collection be made an associative array? This prevents the "rel" attribute from having to be included in the entity's own JSON representation and moves the responsibility of specifying the relationship to the parent object. It also makes the data easier for JavaScript clients to work with IMHO. Ex: "entities": {
"order-items": {
"class": [ "items", "collection" ],
"href": "http://api.x.io/orders/42/items"
},
"customer": {
"class": [ "info", "customer" ],
"properties": {
"customerId": "pj123",
"name": "Peter Joseph"
},
"inline-order-items": [
{
"class": [ "item"],
"properties": {
"itemId": "a123",
"name": "Something"
}
},
{
"class": [ "item"],
"properties": {
"itemId": "a456",
"name": "Something Else"
}
}
]
} |
Two pretty serious issues:
|
Thanks for pointing out my syntax error. I edited my above comment and fixed the example JSON. Yes, rel is the key. My thinking about rel is that the client will typically use it in one of two ways (in the current Siren model): In case A, what I really wanted to write was: var someValue = myObj.entities.customer.properties.myProperty ...but what I end up doing instead is something like: var someValue
var myCustomers = myObj.entities.filter(function(el) { ... })
if (myCustomers && myCustomers.size > 0) {
someValue = myCustomers[0].properties.myProperty
} In case B, I have to write a loop to collect up the values, then (for example) display them as data items in my HTML. Using the proposed style, I can write: var myItems = myObj.entities['inline-order-items']
for (var i = 0; i < myItems.length; i++) {
...
} Using the original syntax, I have to do the same thing but I have to write additional code to filter the list, first: var myItems = myObj.entities.filter(function(el) { ... })
for (var i = 0; i < myItems.length; i++) {
...
} In my thinking, if there are multiple child objects with the same rel, the client has to be smart enough to treat them like a collection anyway. Why not make this association explicit? If the multiplicity of the relationship is unknown, the client can simply test whether the property is an array value or an object value. |
A couple years ago I wrote a client that lets you query siren responses much like you'd use jQuery. for example, get all entities with class var foos = siren('.foo'); It's pretty trivial to do the same thing for rels, etc... I wanted to make it open-source, but my employer at the time did not have a great open source policy. Still, it's not hard to implement, and I've heard of other people doing the same thing with Siren. |
@kevinswiber may have a project available that does something similar. I am pretty sure I remember discussing this type of siren client with him a while back. |
In general I like the idea of moving the That said, a couple of comments on the format @rmorrise provided:
|
see: #17 (comment) |
The purpose of this PR is to relax sub-entity requirements.
rel
.If this change is not implemented in Siren, I will fork Siren.
Rationale